OAuth 2.0 Protected Resource Metadata endpoint by elena-shostak · Pull Request #260773 · elastic/kibana

elena-shostak · 2026-04-01T16:28:51Z

Summary

OAuth 2.0 Protected Resource Metadata endpoint https://datatracker.ietf.org/doc/rfc9728/

xpack.security.mcp.oauth2.metadata:
  authorization_servers:
    - <server1>
    - <server2>
  resource: <resource_uri>
  bearer_methods_supported:
    - header
    - body
    - query
  scopes_supported:
    - all
  resource_documentation: <resource_documentation_uri>

How to test

Add configuration to Kibana

xpack.security.mcp.oauth2.metadata:
  authorization_servers: ['https://localhost:8444/oauth2']
  resource: http://localhost:5601

Note

You may need to add self signed certificate to claude/settings.json
"NODE_EXTRA_CA_CERTS": "<path_to_kibana>/src/platform/packages/shared/kbn-dev-utils/certs/ca.crt"

Start ES and Kibana with UIAM

yarn es serverless --projectType observability --uiam-oauth
yarn start --serverless=oblt --uiam

Login to Kibana
Register Claude as a client

curl --location 'https://localhost:8443/uiam/api/v1/oauth/clients' \
--header 'Content-Type: application/json' \
--header 'Authorization: ApiKey essu_dev_TnpKcmMyVTFkMEo2WW5scU5XUm9PVWw2TVRNNmJqSXRVbWxTVEZNeVowNVRkMWhUVWpCd1l6SjBadz09AAAAAN10T0s=' \
--data '{
    "client_name": "Claude Code",
    "resource": "http://localhost:5601/"
}'

You should get a clientId with response

{
    "id": "<your_client_id>"
    "type": "public",
    "resource": "http://localhost:5601/",
    "creation": "2026-04-01T14:56:04.184718009Z",
    "revoked": false,
    "connections": {
        "active": [],
        "revoked": []
    },
    "client_name": "Claude Code",
    "client_metadata": {}
}

Add Kibana MCP to Claude

claude mcp add --transport http --client-id <your_client_id> kibana-mcp http://localhost:5601/api/agent_builder/mcp

Check the connection

claud mcp list

Should output

kibana-mcp: http://localhost:5601/api/agent_builder/mcp (HTTP) - !Needs authentication

Initiate Claude session and use /mcp to start OAuth flow

Screen.Recording.2026-04-08.at.13.23.44.mov

Checklist

Unit or functional tests were updated or added to match the most common scenarios

Closes: https://github.com/elastic/kibana-team/issues/2750
Relates: #256182

x-pack/platform/plugins/shared/security/server/routes/oauth_metadata/protected_resource.ts

elena-shostak · 2026-04-08T11:41:02Z

x-pack/platform/plugins/shared/security/server/uiam/uiam_service.ts

+    const expectedAudience = this.#kibanaServerURL.endsWith('/')
+      ? this.#kibanaServerURL
+      : `${this.#kibanaServerURL}/`;


Important
Claude's client normalizes the URL to the canonical form with an explicit path. UIAM should treat these as equivalent when comparing, but it doesn't right now, so appending trailing slash as temporary fix, otherwise we would get

Audience mismatch: expected http://localhost:5601 but token has http://localhost:5601/

Let's leave a TODO comment to record that it's a temporary workaround that we should remove.

…ana into 2750-resource-endpoint

elasticmachine · 2026-04-08T15:37:48Z

Pinging @elastic/kibana-security (Team:Security)

src/platform/packages/shared/kbn-es/src/utils/docker_uiam.ts

…ana into 2750-resource-endpoint

elasticmachine · 2026-04-13T12:52:31Z

💛 Build succeeded, but was flaky

Buildkite Build
Commit: 9ed1aac

Failed CI Steps

Test Failures

[job] [logs] affected Scout: [ security / entity_store ] plugin / local-serverless-security_complete - Entity Store History Snapshot - history snapshot: copies latest to history index and resets behaviors on latest
[job] [logs] FTR Configs #141 / Search solution tests Search index details page Solution Nav - Search search index details page has index actions enabled add field button is enabled

Metrics [docs]

Public APIs missing comments

Total count of every public API that lacks a comment. Target amount is 0. Run node scripts/build_api_docs --plugin [yourplugin] --stats comments for more detailed information.

id	before	after	diff
`@kbn/mock-idp-utils`	62	65	+3

Page load bundle

Size of the bundles that are downloaded on every page load. Target size is below 100kb

id	before	after	diff
`mockIdpPlugin`	6.8KB	6.8KB	+31.0B

Unknown metric groups

API count

id	before	after	diff
`@kbn/mock-idp-utils`	70	74	+4

History

azasypkin · 2026-04-13T12:57:36Z

ACK: will review today

azasypkin

Tested locally in Claude Desktop using the config below. The authentication flow and subsequent tool calls worked correctly. LGTM! Just a few nits and questions.

{
  "mcpServers": {
    "oauth-server": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:5601/api/agent_builder/mcp",
        "--static-oauth-client-info",
        "{ \"client_id\": \"XXXX\" }",
        "--static-oauth-client-metadata",
        "{ \"scope\": \"all\" }"
      ],
      "env": {
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

azasypkin · 2026-04-13T16:53:28Z

src/platform/packages/shared/kbn-es/src/utils/docker_uiam.ts

+      '--env',
+      'UIAM_SERVICE_BOUNDARY=external',


nit: we don't need this for cosmos db?

Suggested change

'--env',

'UIAM_SERVICE_BOUNDARY=external',

azasypkin · 2026-04-13T16:59:02Z

src/platform/packages/shared/kbn-es/src/utils/docker_uiam.ts

+    `${KBN_CERT_PATH}:/tmp/server.crt:z`,
+
+    '-p',
+    `127.0.0.1:${+new URL(MOCK_IDP_UIAM_SERVICE_INTERNAL_URL)?.port + 1}:8443`, // UIAM OAuth HTTPS port


nit: now that we two UAIM containers, I think it's time to remove this +new URL(url)?.port and +new URL(url)?.port + 1 logic and just define ports separately for all containers:

const ENV_DEFAULTS = { UIAM_COSMOS_DB_PORT: '8081', UIAM_COSMOS_DB_UI_PORT: '8082', UIAM_SERVICE_PORT: '8443', UIAM_OAUTH_SERVICE_PORT: '8444', UIAM_APP_LOGGING_LEVEL: 'DEBUG', UIAM_LOGGING_LEVEL: 'INFO', };

And then just use env.UIAM_COSMOS_DB_PORT, env.UIAM_SERVICE_PORT, and env.UIAM_OAUTH_SERVICE_PORT.

What do you think?

azasypkin · 2026-04-13T17:10:10Z

src/platform/packages/shared/kbn-es/src/utils/docker_uiam.ts

+ * UIAM external (OAuth) container needs a filesystem path to IdP metadata XML.
+ * Override with `MOCK_IDP_KIBANA_URL`.
+ */
+async function extraDockerParamsForUiamOauthContainer(): Promise<string[]> {


question: cannot we define these params directly on UIAM_OAUTH_CONTAINER, now that we don't write a custom metadata file?

azasypkin · 2026-04-13T17:11:33Z

src/platform/packages/shared/kbn-es/src/utils/docker_uiam.ts

+ * Returns the list of UIAM containers to run.
+ * When `uiamOAuth` is true, includes the UIAM OAuth container.
+ */
+export function getUiamContainers(uiamOAuth?: boolean): UiamContainer[] {


nit: unnamed bool params are a bit hard to read in the consumer code, what about { includeUiamOAuth: boolean } or something like this?

azasypkin · 2026-04-13T17:21:53Z

src/platform/packages/private/kbn-mock-idp-utils/src/utils.ts

+      typeof issuerElement === 'string' ? issuerElement : issuerElement?._ ?? undefined;
+    return {
+      requestId: attrs.ID as string,
+      acsUrl: attrs.AssertionConsumerServiceURL as string | undefined,


optional nit: if it helps to simplify the code here and in MockIdP, we can always hard code ACS as kibana URL + fixed /api/security/saml/callback as we shouldn't support anything else, but feel free to keep everything as is.

azasypkin · 2026-04-13T17:35:30Z

x-pack/platform/plugins/shared/security/server/routes/oauth_metadata/protected_resource.ts

+    }
+  );
+
+  // MCP SDK (RFC 9728) tries path-aware discovery first (e.g.,


nit: direct link to a relevant section of the spec here would also be helpful.

which the SDK

What SDK is meant here?

{path*} vs /.well-known/oauth-protected-resource/api/agent_builder/mcp

Would it make sense to validate that if path is provided it corresponds to /api/agent_builder/mcp?

azasypkin · 2026-04-13T17:41:38Z

x-pack/platform/plugins/shared/security/server/config.ts

+                  schema.literal('header'),
+                  schema.literal('body'),
+                  schema.literal('query'),


nit: would be great to leave a code comment that explains what all these 3 values mean. Do we/UIAM support all of these?

Other fields would probably also benefit from same brief docs.

azasypkin · 2026-04-13T17:42:45Z

x-pack/platform/plugins/shared/security/server/config.ts

 });

 export type UiamConfigType = TypeOf<typeof ConfigSchema>['uiam'];
+export type McpConfigType = TypeOf<typeof ConfigSchema>['mcp'];


nit: it doesn't look we use it anywhere.

Suggested change

export type McpConfigType = TypeOf<typeof ConfigSchema>['mcp'];

azasypkin · 2026-04-13T17:44:07Z

x-pack/platform/plugins/shared/security/server/authentication/authentication_service.ts

        : this.authenticator.getRequestOriginalURL(request);

+      // For routes that accept UIAM OAuth tokens, return a 401 with a WWW-Authenticate header
+      // containing the resource_metadata URL (RFC 9728) instead of redirecting to the login page.


nit: let's leave a direct link to a relevant part of the spec.

azasypkin · 2026-04-13T17:45:04Z

x-pack/platform/plugins/shared/security/server/authentication/authentication_service.ts

+          body: JSON.stringify({
+            jsonrpc: '2.0',
+            id: null,
+            error: { code: -32001, message: 'Unauthorized' },


question: what does this code mean and where is it coming from?

macroscopeapp bot reviewed Apr 1, 2026

View reviewed changes

x-pack/platform/plugins/shared/security/server/routes/oauth_metadata/protected_resource.ts Show resolved Hide resolved

elena-shostak added 4 commits April 8, 2026 11:17

Added resource endpoint

8449b4e

https check

c6cf807

Added env var for uiam-oauth container

8848601

Fixes

ff74af2

elena-shostak force-pushed the 2750-resource-endpoint branch from a031945 to ff74af2 Compare April 8, 2026 10:25

Mock IDP changes

f3a5e96

elena-shostak commented Apr 8, 2026

View reviewed changes

Fixes

5b2a084

kibanamachine and others added 4 commits April 8, 2026 12:09

Changes from node scripts/eslint_all_files --no-cache --fix

9d4a946

Test fixes

5b3e344

Merge branch '2750-resource-endpoint' of github.com:elena-shostak/kib…

f869658

…ana into 2750-resource-endpoint

Merge branch 'main' into 2750-resource-endpoint

52f3878

elena-shostak requested a review from azasypkin April 8, 2026 15:37

elena-shostak marked this pull request as ready for review April 8, 2026 15:37

elena-shostak requested review from a team as code owners April 8, 2026 15:37

Ikuni17 reviewed Apr 8, 2026

View reviewed changes

src/platform/packages/shared/kbn-es/src/utils/docker_uiam.ts Outdated Show resolved Hide resolved

elena-shostak and others added 5 commits April 13, 2026 11:07

Reused SERVERLESS_IDP_METADATA_PATH for uiam-oauth container

6b8678b

Moved UIAM_OAUTH to --uiam-oauth CLI flag

b8a6eeb

Changes from node scripts/lint_ts_projects --fix

55119b4

Changes from node scripts/regenerate_moon_projects.js --update

f5591a2

Test fixes

635a231

elena-shostak and others added 2 commits April 13, 2026 13:11

Merge branch '2750-resource-endpoint' of github.com:elena-shostak/kib…

106784f

…ana into 2750-resource-endpoint

Merge branch 'main' into 2750-resource-endpoint

9ed1aac

Ikuni17 approved these changes Apr 13, 2026

View reviewed changes

azasypkin approved these changes Apr 13, 2026

View reviewed changes

Conversation

elena-shostak commented Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

How to test

Checklist

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

elasticmachine commented Apr 8, 2026

Uh oh!

Uh oh!

elasticmachine commented Apr 13, 2026

💛 Build succeeded, but was flaky

Failed CI Steps

Test Failures

Metrics [docs]

Public APIs missing comments

Page load bundle

API count

History

Uh oh!

azasypkin commented Apr 13, 2026

Uh oh!

azasypkin left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

elena-shostak commented Apr 1, 2026 •

edited

Loading